import { Callout } from '@theguild/components'

# First Steps

Using Envelop is straight-forward and intuitive, in this section you will learn how to install and
set up a GraphQL server using Envelop from scratch.

<Callout>
  In case you are being referred to the Envelop documentation from a framework or library that
  implements envelop, you can straight dive into the [Plugin Hub](/plugins) or head over to the
  [Plugin Tutorial](/docs/plugins) for learning how to write your plugins.
</Callout>
## Installation

Start by adding the core of `envelop` and `graphql` to your codebase.

```sh npm2yarn
npm i @envelop/core graphql
```

## Create Your First Envelop

After installing the `@envelop/core` package, you can use the `envelop` function for creating your
`getEnveloped` function. We use a simple GraphQL schema that we build with the `buildSchema`
function from `graphql`.

```ts
import * as GraphQLJS from 'graphql'
import { envelop, useEngine, useSchema } from '@envelop/core'

const schema = buildSchema(/* GraphQL */ `
  type Query {
    hello: String
  }
`)

export const getEnveloped = envelop({
  plugins: [useSchema(schema)]
})
```

## Use Your Envelop

The result of `envelop` is a factory function that allows you to get everything you need for the
GraphQL execution: `parse`, `validate`, `contextBuilder`, `execute` and `subscribe`. It is usually
named `getEnveloped`.

By calling the `getEnveloped` function you will get all the primitive functions required for the
GraphQL execution layer.

```ts
// prettier-ignore
const {
  contextFactory,
  parse,
  validate,
  execute,
  subscribe,
  schema,
} = getEnveloped()
```

## Add Plugins to Your Envelop

After you set up your base Envelop, you can start customizing your GraphQL server. Adding new
functionality is as easy as adding a new envelop plugin to your base envelop setup.

Let's add a parser and validation cache, so sending the same operation string sent to our server is
cached using an LRU cache, allowing to improve the overall performance of the GraphQL execution
layer.

```sh npm2yarn
npm i @envelop/parser-cache @envelop/validation-cache
```

```ts
import { buildSchema } from 'graphql'
import { envelop, useEngine, useSchema } from '@envelop/core'
import { useParserCache } from '@envelop/parser-cache'
import { useValidationCache } from '@envelop/validation-cache'

const schema = buildSchema(/* GraphQL */ `
  type Query {
    hello: String
  }
`)

const getEnveloped = envelop({
  plugins: [
    // all enabled plugins
    useSchema(schema),
    useParserCache(),
    useValidationCache()
  ]
})
```

<Callout>A list of all available plugins can be found in the [Plugins](/plugins) page.</Callout>

## Use Your Envelop with an HTTP Server

You can build a very simple GraphQL HTTP server from scratch, by using the Node.js `http` module and
only these functions.

```ts
import { createServer } from 'node:http'
import { GraphQLError } from 'graphql'
import { getEnveloped } from './envelop'

const httpServer = createServer(async (req, res) => {
  try {
    // body parsing
    req.body = await new Promise((resolve, reject) => {
      let data = ''
      req.on('data', chunk => {
        data += String(chunk)
      })
      req.on('end', () => {
        resolve(data)
      })
      req.on('error', err => reject(err))
    })

    const {
      // Get the GraphQL execution functions with attached plugin handlers
      parse,
      validate,
      contextFactory,
      execute,
      schema
      // pass in an initial context that all plugins can consume and extend
    } = getEnveloped({ req })

    // Parse request body JSON
    const { query, variables } = JSON.parse(req.body)
    const document = parse(query)
    const validationErrors = validate(schema, document)

    if (validationErrors.length > 0) {
      return res.end(JSON.stringify({ errors: validationErrors }))
    }

    // Build the context and execute
    const contextValue = await contextFactory()
    const result = await execute({
      document,
      schema,
      variableValues: variables,
      contextValue
    })

    // Send the response
    res.end(JSON.stringify(result))
  } catch (err) {
    if (err instanceof GraphQLError === false) {
      err = new GraphQLError(err.message)
    }
    res.end(JSON.stringify({ errors: [err] }))
  }
})

httpServer.listen(3000)
```

After starting this server we can send a GraphQL operation using `curl`, yielding a response of
`{"data":{"__typename":"Query"}}{:json}`.

```bash
curl \
  -X POST \
  -d '{"query":"{__typename}"}' \
  http://localhost:3000
```

<Callout>
  This example uses the Node.js `http` module and is a very simplified handler that does not
  strictly follow the [GraphQL over HTTP
  specification](https://github.com/graphql/graphql-over-http) as it does not handle headers or
  respect HTTP methods. For actual production usage, we recommend using Envelop with one of the
  popular and battle-tested HTTP frameworks and servers. Check the examples on our [Integrations
  page](/docs/integrations).
</Callout>
